{ /* This Source Code Form is subject to the terms of the Mozilla Public
  License, v. 2.0. If a copy of the MPL was not distributed with this
  file, You can obtain one at http://mozilla.org/MPL/2.0/.

  Copyright (c) KALEIDOS INC */ }

import { Canvas, Meta } from '@storybook/addon-docs/blocks';
import * as SelectStories from "./select.stories";

<Meta title="Controls/Select" />

# Select

The `select*` component lets users choose one option from an options menu.

## Variants

We will use the text-only variant when there are enough space and icons don't add any useful context.

<Canvas of={SelectStories.Default} />

We will use the icon and text variant when there are enough space and icons add any useful context.

<Canvas of={SelectStories.WithIcons} />

If we consider that empty options have a special meaning, we can move them to the end of the list, to a section separate from the rest.

<Canvas of={SelectStories.EmptyToEnd} />

## Technical notes

### Icons

Each option of `select*` may accept an `icon`, which must contain an [icon ID](../foundations/assets/icon.mdx).
These are available in the `app.main.ds.foundations.assets.icon` namespace.

### Dimmed
Each option can have an optional parameter `dimmed` with value `true` to show the option dimmed


```clj
(ns app.main.ui.foo
  (:require
   [app.main.ui.ds.foundations.assets.icon :as i]))
```

```clj
[:> select*
    {:options [{ :label "Code"
                 :id "option-code"
                 :icon i/fill-content }
               { :label "Design"
                 :id "option-design"
                 :icon i/pentool }
               { :label "Menu"
                 :id "option-menu"
                 :dimmed true }
               ]}]
```

## Usage guidelines (design)

### Where to use

Used in a wide range of applications in the app,
to select among available text-based options,
sometimes with icons that offers additional context.

### When to use

Consider using select when you have 5 or more options to choose from.

### Interaction / Behavior

When the user clicks on the clickable area, a list of
options appears. When an option is chosen, the list is closed.